home *** CD-ROM | disk | FTP | other *** search
/ SGI Developer Toolbox 6.1 / SGI Developer Toolbox 6.1 - Disc 1.iso / toolbox / documents / OpenGL / extensions / spec / copy_texture.spec < prev    next >
Encoding:
Text File  |  1996-11-11  |  10.9 KB  |  307 lines
  1. Name
  2.  
  3.     EXT_copy_texture
  4.  
  5. Name Strings
  6.  
  7.     GL_EXT_copy_texture
  8.  
  9. Version
  10.  
  11.     $Date: 1995/09/30 02:31:03 $ $Revision: 1.1 $
  12.  
  13. Number
  14.  
  15.     10
  16.  
  17. Dependencies
  18.  
  19.     EXT_texture is required.
  20.     EXT_texture3D affects the definition of this extension.
  21.     SGIS_texture_filter4 affects the definition of this extension.
  22.     EXT_subtexture affects the definition of this extension.
  23.  
  24. Overview
  25.  
  26.     This extension defines methods to load texture images directly from the
  27.     framebuffer.  Methods are defined for both complete and partial
  28.     replacement of a texture image.  Because it is not possible to define
  29.     an entire 3D texture using a 2D framebuffer image, 3D textures are
  30.     supported only for partial replacement.
  31.  
  32. New Procedures and Functions
  33.  
  34.     void CopyTexImage1DEXT(enum target,
  35.                int level,
  36.                enum internalformat,
  37.                int x,
  38.                int y,
  39.                sizei width,
  40.                int border);
  41.  
  42.     void CopyTexImage2DEXT(enum target,
  43.                int level,
  44.                enum internalformat,
  45.                int x,
  46.                int y,
  47.                sizei width,
  48.                sizei height,
  49.                int border);
  50.  
  51.     void CopyTexSubImage1DEXT(enum target,
  52.                   int level,
  53.                   int xoffset,
  54.                   int x,
  55.                   int y,
  56.                   sizei width);
  57.  
  58.     void CopyTexSubImage2DEXT(enum target,
  59.                   int level,
  60.                   int xoffset,
  61.                   int yoffset,
  62.                   int x,
  63.                   int y,
  64.                   sizei width,
  65.                   sizei height);
  66.  
  67.     void CopyTexSubImage3DEXT(enum target,
  68.                   int level,
  69.                   int xoffset,
  70.                   int yoffset,
  71.                   int zoffset,
  72.                   int x,
  73.                   int y,
  74.                   sizei width,
  75.                   sizei height);
  76.  
  77. New Tokens
  78.  
  79.     None
  80.  
  81. Additions to Chapter 2 of the 1.0 Specification (OpenGL Operation)
  82.  
  83.     None
  84.  
  85. Additions to Chapter 3 of the 1.0 Specification (Rasterization)
  86.  
  87.     CopyTexImage1DEXT and CopyTexImage2DEXT are related to TexImage1D and
  88.     TexImage2D in exactly the way that CopyPixels is related to DrawPixels.
  89.     Rather than accepting image data from memory, they copy image data from
  90.     the color buffer specified by the current ReadBuffer mode.
  91.     CopyTexImage2DEXT accepts image data from a width+2*border pixel wide by
  92.     height+2*border pixel high color buffer region whose lower-left pixel
  93.     has window coordinates <x>,<y>.  If any pixels within this region are
  94.     outside the window that is associated with the GL context, the values
  95.     obtained for those pixels are undefined.  These pixel values are
  96.     processed exactly as if CopyPixels had been called, but the process
  97.     stops just before final conversion.  At this point all pixel component
  98.     values are clamped to [0,1], and then treated exactly as if TexImage2D
  99.     had been called.  Pixel ordering is such that lower X screen coordinates
  100.     correspond to lower i texture coordinates, and lower Y screen
  101.     coordinates correspond to lower j texture coordinates (refer to Figure
  102.     3.10 - A texture image and the coordinates used to access it, GL
  103.     Specification).  The semantics and accepted values of the <target>,
  104.     <level>, and <border> parameters are exactly equivalent to their
  105.     TexImage2D counterparts, except that <target> does not accept
  106.     PROXY_TEXTURE_2D_EXT.  The semantics of <internalformat> are identical
  107.     to those of the <components> parameter of TexImage2D, except that
  108.     values 1, 2, 3, and 4 are not accepted by CopyTexImage2DEXT.
  109.  
  110.     CopyTexImage1DEXT accepts image data from a width+2*border pixel wide
  111.     by 1 pixel high color buffer region whose left-most pixel has window
  112.     coordinates <x>,<y>.  If any pixels within this region are outside the
  113.     window that is associated with the GL context, the values obtained for
  114.     those pixels are undefined.  The pixels are processed just as those of
  115.     CopyTexImage2DEXT are, and they define a texture such that lower X
  116.     window coordinates correspond to lower i texture coordinates, as per
  117.     Figure 3.10 of the GL Specification.  The semantics and accepted values
  118.     of the <level>, <border>, and <internalformat> parameters are exactly
  119.     those of CopyTexImage2DEXT.  <target> accepts only TEXTURE_1D.
  120.     
  121.     If EXT_subtexture is supported, this extension also defines
  122.     CopyTexSubImage1DEXT and CopyTexSubImage2DEXT.  These commands are
  123.     related to TexSubImage1DEXT and TexSubImage2DEXT in exactly the way
  124.     that CopyPixels is related to DrawPixels.  Rather than accepting image
  125.     data from memory, they copy image data from the framebuffer.  The
  126.     semantics and accepted values of the <target>, <level>, <xoffset>, and
  127.     <yoffset> parameters are exactly equivalent to their TexSubImage1DEXT
  128.     and TexSubImage2DEXT counterparts.  The semantics and accepted values
  129.     of the <x>, <y>, <width>, and <height> parameters are exactly equivalent
  130.     to their CopyTexImage1DEXT and CopyTexImage2DEXT counterparts.
  131.  
  132.     If EXT_subtexture and EXT_texture3D are both supported, this extension
  133.     also defines CopyTexSubImage3DEXT.  Because framebuffer memory is two-
  134.     dimensional, only a portion of a single s,t slice of a 3D texture is
  135.     replaced by this command.  Thus CopyTexSubImage3DEXT is related to
  136.     TexSubImage3DEXT in exactly the way that CopyPixels is related to
  137.     DrawPixels, except that it is as though TexSubImage3DEXT parameter
  138.     <depth> were 1.  Rather than accepting image data from memory,
  139.     CopyTexSubImage3DEXT copies image data from the framebuffer.  The
  140.     semantics and accepted values of the <target>, <level>, <xoffset>,
  141.     <yoffset>, and <zoffset> parameters are exactly equivalent to their
  142.     TexSubImage3DEXT counterparts.  The semantics and accepted values of
  143.     the <x>, <y>, <width>, and <height> parameters are exactly equivalent
  144.     to their CopyTexImage2DEXT counterparts.
  145.  
  146. Additions to Chapter 4 of the 1.0 Specification (Per-Fragment Operations
  147. and the Framebuffer)
  148.  
  149.     None
  150.  
  151. Additions to Chapter 5 of the 1.0 Specification (Special Functions)
  152.  
  153.     None
  154.  
  155. Additions to Chapter 6 of the 1.0 Specification (State and State Requests)
  156.  
  157.     None
  158.  
  159. Additions to the GLX Specification
  160.  
  161.     None
  162.  
  163. GLX Protocol
  164.  
  165.     Five new GL rendering commands are added. The following commands are sent to the
  166.     server as part of a glXRender request:
  167.  
  168.     CopyTexImage1DEXT
  169.             2           32              rendering command length
  170.             2           4119            rendering command opcode
  171.             4           ENUM        target
  172.         4            INT32           level
  173.         4        ENUM        internalformat
  174.         4         INT32        x    
  175.         4         INT32        y    
  176.         4         INT32        width
  177.         4         INT32        border
  178.  
  179.         CopyTexImage2DEXT
  180.             2           36              rendering command length
  181.             2           4120            rendering command opcode
  182.             4           ENUM        target
  183.         4            INT32           level
  184.         4        ENUM        internalformat
  185.         4         INT32        x    
  186.         4         INT32        y    
  187.         4         INT32        width
  188.         4         INT32        height
  189.         4         INT32        border
  190.  
  191.         CopyTexSubImage1DEXT
  192.             2           28              rendering command length
  193.             2           4121            rendering command opcode
  194.             4           ENUM        target
  195.         4            INT32           level
  196.         4            INT32           xoffset
  197.         4         INT32        x    
  198.         4         INT32        y    
  199.         4         INT32        width
  200.  
  201.         CopyTexSubImage2DEXT
  202.             2           36              rendering command length
  203.             2           4122            rendering command opcode
  204.             4           ENUM        target
  205.         4            INT32           level
  206.         4            INT32           xoffset
  207.         4            INT32           yoffset
  208.         4         INT32        x    
  209.         4         INT32        y    
  210.         4         INT32        width
  211.         4         INT32        height
  212.  
  213.         CopyTexSubImage3DEXT
  214.             2           40              rendering command length
  215.             2           4123            rendering command opcode
  216.             4           ENUM        target
  217.         4            INT32           level
  218.         4            INT32           xoffset
  219.         4            INT32           yoffset
  220.         4            INT32           zoffset
  221.         4         INT32        x    
  222.         4         INT32        y    
  223.         4         INT32        width
  224.         4         INT32        height
  225.  
  226. Dependencies on EXT_texture
  227.  
  228.     EXT_texture is required.  This extension builds on the notion of
  229.     internal image format, which is defined by EXT_texture.
  230.  
  231. Dependencies on EXT_texture3D
  232.  
  233.     If EXT_texture3D is not supported, CopyTexSubImage3DEXT is not defined
  234.     by this extension.
  235.  
  236. Dependencies on SGIS_texture_filter4
  237.  
  238.     If SGIS_texture_filter4 is not supported, 2 is not accepted as a border
  239.     value.
  240.  
  241. Dependencies on EXT_subtexture
  242.  
  243.     If EXT_subtexture is not supported, CopyTexSubImage1DEXT,
  244.     CopyTexSubImage2DEXT, and CopyTexSubImage3DEXT are not defined by this
  245.     extension.
  246.  
  247. Errors
  248.  
  249.     INVALID_ENUM is generated if CopyTexImage1DEXT or CopyTexSubImage1DEXT
  250.     parameter <target> is not TEXTURE_1D.  (The commands defined by this
  251.     extension do not accept PROXY targets.)
  252.  
  253.     INVALID_ENUM is generated if CopyTexImage2DEXT or CopyTexSubImage2DEXT
  254.     parameter <target> is not TEXTURE_2D.
  255.  
  256.     INVALID_ENUM is generated if CopyTexSubImage3DEXT parameter <target>
  257.     is not TEXTURE_3D_EXT.
  258.  
  259.     INVALID_VALUE is generated if CopyTexImage1DEXT or CopyTexImage2DEXT
  260.     parameter <level> is less than zero, or greater than the maximum value
  261.     supported by the implementation.
  262.  
  263.     INVALID_ENUM is generated if CopyTexImage1DEXT or CopyTexImage2DEXT
  264.     parameter <internalformat> is not RED, GREEN, BLUE, ALPHA, RGB, RGBA,
  265.     LUMINANCE, LUMINANCE_ALPHA, or one of the token values defined by
  266.     EXT_texture.
  267.  
  268.     INVALID_VALUE is generated when any of the <width>, <height> or <depth>
  269.     parameters of CopyTexImage1DEXT, CopyTexImage2DEXT, or CopyTexImage3DEXT
  270.     is less than zero, or if it cannot be represented as 2**k + 2*border
  271.     for some integer k.
  272.  
  273.     INVALID_VALUE is generated if CopyTexSubImage1DEXT, CopyTexSubImage2DEXT,
  274.     or CopyTexSubImage3DEXT parameter <xoffset>, CopyTexSubImage2DEXT or
  275.     CopyTexSubImage3DEXT parameter <yoffset>, or CopyTexSubImage3DEXT
  276.     parameter <zoffset> is less than -TEXTURE_BORDER, where TEXTURE_BORDER
  277.     is the border width of the texture array to be modified.
  278.  
  279.     INVALID_VALUE is generated if CopyTexSubImage1DEXT, CopyTexSubImage2DEXT,
  280.     or CopyTexSubImage3DEXT (xoffset + width) > (TEXTURE_WIDTH -
  281.     TEXTURE_BORDER), or if CopyTexSubImage2DEXT or CopyTexSubImage3DEXT
  282.     (yoffset + height) > (TEXTURE_HEIGHT - TEXTURE_BORDER), or if
  283.     CopyTexSubImage3DEXT zoffset >= (TEXTURE_DEPTH_EXT - TEXTURE_BORDER).
  284.     Note that TEXTURE_WIDTH, TEXTURE_HEIGHT, and TEXTURE_DEPTH_EXT include
  285.     twice the border width.
  286.  
  287.     TEXTURE_TOO_LARGE_EXT is generated by CopyTexImage1DEXT or
  288.     CopyTexImage2DEXT if the specified image is too large, for any reason.
  289.     (See EXT_texture for a discussion of how applications can query the
  290.     maximum texture size.)
  291.  
  292.     INVALID_VALUE is generated if CopyTexImage1DEXT or CopyTexImage2DEXT
  293.     parameter <border> is not 0, 1, or 2.
  294.  
  295.     INVALID_OPERATION is generated if CopyTexImage1DEXT, CopyTexImage2DEXT,
  296.     CopyTexSubImage1DEXT, CopyTexSubImage2DEXT, or CopyTexSubImage3DEXT is
  297.     called between execution of Begin and the corresponding execution of
  298.     End.
  299.  
  300. New State
  301.  
  302.     None
  303.  
  304. New Implementation Dependent State
  305.  
  306.     None
  307.